---
title: SAIF.Business.Utilities architecture
summary: Architectural responsibilities, boundaries, and interaction patterns.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-08-21
library: SAIF.Business.Utilities
reference_type: embedded
---

# SAIF.Business.Utilities architecture

`SAIF.Business.Utilities` is a leaf, stateless text-formatting utility library. Despite its `SAIF.Business.*` name, it contains no business entities, BOF business objects, persistence, or service calls — it exists solely to normalize legacy uppercase-stored text into display-ready casing and to render numbers as English words.

## Responsibilities
- Convert free-form name/address/description text (typically all-caps legacy data) into display-ready title case while preserving original delimiter characters, via `TitleCase.ToTitleCase` and its extension-method façade `TitleCaseExtensions.ToTitleCase`.
- Provide supporting casing helpers: `ToProperCase`, `ToPadCapitalLetters`, `ToLower`, `ToUpper`, `ContainsOnlyNumericCharacters`.
- Render whole numbers as English words via `mdlTextConversion.NumberToText` (e.g. for written amounts on legal/printed output*).
- Normalize a string to sentence casing via `mdlTextConversion.ToSentenceCase`.

## Component boundaries
- `TitleCase` (class) + `TitleCaseExtensions` (module): a rules-driven casing engine and its extension-method surface. All members are `Shared`; word lists are immutable `Private Shared` arrays, so the component holds no instance state*.
- `mdlTextConversion` (module): number-to-words conversion and sentence casing, independent of the `TitleCase` component — the two components have no coupling between them.
- Both components are `Public Module`/`Shared`-only, so importing the `SAIF.Business.Utilities` namespace silently adds `ToTitleCase`, `ToProperCase`, `ToPadCapitalLetters`, `ToLower`, `ToUpper`, `ContainsOnlyNumericCharacters`, and `ToSentenceCase` extension methods to `String`/`String()` across the consuming project — a wide ambient surface that is a notable coupling characteristic*.

## Interaction model
- The library has no outbound in-repo project references — it is a leaf/foundation library depending only on the BCL, `Microsoft.VisualBasic`, and the shared `SAIF.Framework.Common` extension/format helpers (`ToStringAll`, `IsIn`, `TakeFromEnd`, `PadCapitalLettersFormat`)*.
- Within this repository it is consumed only by `SAIF.Business.View.Policy`, which calls `.ToTitleCase` on `PolicyName` and `PolicyStatusDescription` in `clsPolicyAssociation.vb`, confirming this library sits below the view/presentation-model layer as a formatting service*.
- Calls are synchronous, in-process method/extension-method invocations with no persistence or external service interaction.

## Architecture diagram
The following diagram shows the two independent components and their only in-repo consumer.

```mermaid
flowchart TD
	A[SAIF.Business.View.Policy<br>clsPolicyAssociation] --> B[TitleCaseExtensions.ToTitleCase]
	B --> C[TitleCase.ToTitleCase]
	C --> D[SAIF.Framework.Common<br>PadCapitalLettersFormat, extensions]
	E[mdlTextConversion<br>NumberToText / ToSentenceCase]
```

## Sequence diagram
The following diagram shows the primary request/response sequence for title-casing a display value.

```mermaid
sequenceDiagram
	participant Caller as clsPolicyAssociation
	participant Ext as TitleCaseExtensions
	participant Core as TitleCase
	Caller->>Ext: PolicyName.ToTitleCase()
	Ext->>Core: ToTitleCase(inString)
	Core-->>Ext: title-cased string
	Ext-->>Caller: title-cased string
```

## Design constraints
- Statelessness: all members are `Shared`/module-level with immutable word lists, so calls are side-effect free and thread-safe*.
- Recursion depth in `TitleCase.ReassembleString` scales with word count, and in `mdlTextConversion.NumberToText` scales with numeric magnitude*.
- No `Try/Catch` guards `TitleCase.ToTitleCase`; a source string whose delimiter positions do not align with the reassembly index can surface an index-out-of-range exception**.
- The nested `Tests/Tests.vbproj` (MbUnit) documents the expected casing contract but is not listed in `LegalMaintenance.sln`, so it is not built or run by the repository build*.

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with ** could not be confirmed; treat as unknown until verified.

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [API reference](api/index.md)

## Sources
- `SAIF.Business.Utilities/TitleCase.vb`
- `SAIF.Business.Utilities/TitleCaseExtensions.vb`
- `SAIF.Business.Utilities/mdlTextConversion.vb`
- `SAIF.Business.Utilities/SAIF.Business.Utilities.vbproj`